Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d16 / pbwindow.arc / PBWINDOW.DOC < prev next >

Wrap

Text File | 1990-09-10 | 89.2 KB | 2,476 lines

┌────────────────────────┐ │ │ │ Windows for │ │ PowerBasic │ │ ╔════ 2.10 ═════╗ │ └────║ PBWindow.PBU ║───┘ ║ Documentation ║ ┌─────────────╚═══════════════╝─────────────┐ │ Copyright (c) 1987,88,89,90 Barry Erick │ │ 75300,214 Compuserve │ │ B.ERICK GEnie │ └───────────────────────────────────────────┘ ┌─────────┐ ┌─────┴───┐ │ (tm) ──│ │o │────────────────── │ ┌─────┴╨──┐ │ Association of │ │ │─┘ Shareware └───│ o │ Professionals ──────│ ║ │──────────────────── └────╨────┘ MEMBER ContentsContents 1 Highlights . . . . . . . . . . . . . . . . . . 1 2 What is PBWindow . . . . . . . . . . . . . . . 4 3 How to use PBWindow with your programs . . . . 4 4 PBWindow Routines . . . . . . . . . . . . . . 6 5 The Demo PWDemo.Bas . . . . . . . . . . . . . 20 6 Potpourri . . . . . . . . . . . . . . . . . . 20 6.1 Support available . . . . . . . . . . . . 20 6.2 Source Code Available . . . . . . . . . . 20 6.3 Update availability . . . . . . . . . . . 21 6.4 Distribution of the programs . . . . . . 21 6.5 Warranty and Disclaimer . . . . . . . . . 23 6.6 Copyright Notices . . . . . . . . . . . . 23 Appendix A Public Variables 25 Appendix B Error Codes 29 Appendix C SHAREWARE 31 C.1 Definition of Shareware . . . . . . . . . . 31 C.2 Ombudsman . . . . . . . . . . . . . . . . . 31 Index 33 i ii TablesTables Table 1: Colors for Fc,Bc,Bfc, and Bbc . . . . . . . .8 Table 2: Box Title Locations . . . . . . . . . . . . 10 Table 3: Bars Generated . . . . . . . . . . . . . . 15 iii 1 Highlights 1 Highlights PBWindow.PBU version 2.10 has these features: o For PowerBASIC 2.1 Power Pak. Another version is available for PowerBASIC version 2.0x. o Zoom windows. A procedure allows you to zoom windows onto the screen. o Tracking of all window attributes so when the window is active, the window can be worked with, changed, and restored to the original. This allows you to use the window pointer (Wpt%) to reference any window and make changes to it, if it is not overlaid by another window. o Noise can be turned off, even if a window requests it. o You can recolor a window instantly. o By changing one variable in the Include file, you can specify a minimum of 5 windows to a maximum limited by memory and the size of your program. Since PowerBasic no longer limits strings to 64k, and the windows are saved in strings, PBWindow takes advantage of these new strings. All inline routines were changed to a Object code in this version. Some Functions are now built-in in PowerBasic. o Ability to automatically make a menu selection. o 12 Title area in a screen: - Top Left - Top Center - Top Right - Bottom Left - Bottom Center - Bottom Right - Top Left Vertical Side - Middle Left Vertical Side - Lower Left Vertical Side - Top Right Vertical Side - Middle Right Vertical Side - Lower Right Vertical Side o Both vertical and horizontal centering within a box. (c) 1987-90 Barry Erick Page 1 (c) 1987-90 Barry Erick Page 1 PBWindow DocumentationPBWindow Documentation o 13 kinds of windows: - Blank (no outline) - Blank (no outline, no borders) - Single line outline, top, bottom and sides - Double line outline, top, bottom and sides - Double Vertical line outline, single Horizontal line outline - Single Vertical line outline, double Horizontal line outline - Single horizontal outline, no vertical outline - Single horizontal outline, no vertical outline, no vertical border - Double horizontal outline, no vertical outline - Double horizontal outline, no vertical outline, no vertical border - Solid block outline, top, bottom, and sides - Light hatch outline, top, bottom, and sides - Medium hatch outline, top, bottom, and sides - Heavy hatch outline, top, bottom, and sides o 10 kinds of shadows: - None - Left solid drop shadow - Right solid drop shadow - Left transparent drop shadow - Right transparent drop shadow - Left light hatch drop shadow - Right light hatch drop shadow - Left medium hatch drop shadow - Right medium hatch drop shadow - Left heavy hatch drop shadow - Right heavy hatch drop shadow o Clear individual lines in a window o Change attributes in a window on a line by line basis o 5 kinds of menus - No highlight - The item is highlighted - The item line is highlighted - An arrow is used - An arrow is used and the item is highlighted o Restore a title outline after removing the title. Page 2 (c) 1987-90 Barry Erick Page 2 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation o Hercules and IBM Mono compatibility. While this was developed for color enviroments, it works fine for a mono mode. o The ability to catch errors in writing programs by setting a variable, UnderDevelopment%, to %True, and then disable this by making it %False once your program is developed. o Movement of all $Inline code to Object code. (c) 1987-90 Barry Erick Page 3 (c) 1987-90 Barry Erick Page 3 PBWindow DocumentationPBWindow Documentation 2 What is PBWindow 2 What is PBWindow PBWindow.PBU and PBWindow.INC allows you to add pop-up windows to your PowerBasic programs. There are 22 Public routines in PBWindow that you can access from your program: 1. FUNCTION GetAttribute 12. SUB PrtEOL 2. SUB GetForAndBack 13. SUB PrtEOLBox 3. SUB PrtBox 14. SUB NewBoxColor 4. SUB Rackett 15. SUB BuildMenu 5. SUB RemoveBox 16. SUB PrtAttrBox 6. SUB BoxTitle 17. SUB ClearBox 7. SUB MakeBox 18. SUB Recolor 8. SUB ZoomBox 19. SUB WriteScreenArea 9. SUB BoxScroll 20. SUB SaveScreenArea 10. SUB CtrBox 21. SUB PBWindowInit 11. SUB CtrAllBox 22. SUB ScreenInit 4 routines are in the PBWOBJ.OBJ file that by the nature of being in the obj code are PUBLIC. They are : 1. SUB WritVidP 2. SUB ReadVidP 3. SUB Scroll 4. FUNCTION WhatCpu% 3 How to use PBWindow with your programs 3 How to use PBWindow with your programs It is real easy to add PBWindow to your program. The only code need to compile is: $INCLUDE "PBWINDOW.INC" near the start of your program. By near, we mean you may need some metastatements in front of this, and a DEFINT A-Z, as the unit uses this and the $Include expects this. You should set the variable Max.Window% to some value greater than the default of 5 by placing the statement Max.Window% = nn where n is 5 or greater. The demo uses 14. One Constant MUST be used. This is %PBWSmall = 0 . For the registered versions, this means something. For the non registered versions, this must be used for the compile to work, but can be ignored otherwise. You may want to add this to the INCLUDE file for simplicity. See the demo source for other Constants. Also, the variable AutoBuildTime% may 1 be set. If not, it defaults to 30 seconds . A command line option _________________________________________________________________ 1. The demo starts out with this value, and then, if this value is reached without a key being hit, it speeds up the showing by using a 5 second delay. Page 4 (c) 1987-90 Barry Erick Page 4 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation allows the overriding by specifying a value of 20 to 15000 seconds. To use this, start PWDemo like this: PWDemo /300 and substitute the desired time for the 300. In the example, the time delay will be 300 seconds. The two files needed to compile are PBWindow.INC and PBWindow.PBU. The first file should reside in your Include directory and the second in the Unit Source directory. This will allow a compile to take place. However, unless you add code to your program to make windows and use them, the compiled code is useless. The steps are: 1. Place PBWindow.INC in your Include directory 2. Place PBWindow.PBU in your PBU directory 3. Place PBWObj.OBJ in your OBJ directory 4. Place the statement Max.Window% = nn where nn is the maximum number of windows you need open at one time. 14 is a good number, while 5 is the minimum and default if you try to set it to a lesser number. Set the constant %PBWSmall to 0. A typical statement would be: Max.Window% = 14 %PBWSmall = 0 5. Place the $INCLUDE metastatement to your program to bring in the PBWindow.INC file. If you have this in your INC directory and have saved your configuration so PowerBasic knows where to find files (see Options/Directories and Options/Save in the PowerBasic manuals or menus or help). A typical statement would be: $INCLUDE "PBWindow.INC" 6. Make sure the file PBWOBJ.OBJ is in your current directory, the PB Object directory, or your path, as this file is necessary.You may then set the variable UnderDevelopment% to %True to allow error checks on code you send to the PBWindow.PBU file. Once done with the development, you can either remove this code or make it %False. It defaults to %False. To enable it, the statement would be: UnderDevelopment% = %True and to disable it, you would either remove it or change it to: UnderDevelopment% = %False 7. The Include file sets the default variable type to be integer, so if your program does not have a DEFINT or other DEFxxx statement in it, the default variable type will be Integer and not single precision. This is an (c) 1987-90 Barry Erick Page 5 (c) 1987-90 Barry Erick Page 5 PBWindow DocumentationPBWindow Documentation important point, if some routines no longer work when you add PBWindows to them. It is perfectly safe to place a DEFnnn statement after the $INCLUDE metastatement for the rest of your program to default to your type. Note that all calls to PBWindow routines require either Integer or String variables and constants. 8. Add the various PBWindow statements to your program to add the windows. Note that you have to Make A Box before you can Print To A Box. A box is the same as a window, and may be referenced to in either way in this documentation. To compile the demo, simply load PWDemo.Bas into the IDE and press Alt-F9 or F10/Compile/Compile. From the PBC, simply type PBC PWDemo -CE. All command switching has been taken care of in the program. Note that the demo expects to find DayDate.PBU and PbWindow.PBU in either your default directory or PBUDestination library. The object files, PBWObj.OBJ and CPU.Obj are expected in your default library or PBObj library and PBWindow.INC in your default or INClude directory. The files DayDate and CPU are only used in the demo and are not needed to use PBWindow.PBU, PBWObj.OBJ and PbWindow.INC. Details to the use of DayDate.PBU and/or CPU.Obj are in the PWdemo.Bas source file. Additional details may be in a file called Readme if necessary. 4 PBWindow Routines 4 PBWindow Routines There are three main routines to PBWindows, MakeBox, ZoomBox and RemoveBox. MakeBox or ZoomBox are the first procedures to call to make a window, and RemoveBox is the last called, to remove the window. The rest of the 22 routines support these two main routines. MakeBox This routine makes a box. Your limit on the MakeBox maximum number of windows open at any time is set with the Max.Window% variable. The calling sequence is: Call MakeBox(Wr%,Wc%,Wh%,Ww%,fc%,bc%,_ BoxKind%,Shadow%,Racket%,Bfc%,Bbc%) Where: Wr% WindowRow. The row on the screen Wr% where the windows top row shall be placed. Wc% WindowColumn. The Column on the Wc% screen where the windows left side will be placed. Page 6 (c) 1987-90 Barry Erick Page 6 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Wh% WindowHeight. The number of rows Wh% (not the row number) that the height of the window will take. This must be two more than the number of rows you plan to place within the window. Ww% WindowWidth. The number of Ww% columns (not the column number) that the column will take. fc% ForegroundColor. This is the fc% color the text within the box will take. See Table 1 for valid numbers. bc% BackgroundColor. This is the bc% color the text within the box will take as its background. See table 1 for valid numbers. BoxKind% This defines if there will be a BoxKind% outline around the window. There are 11 legal values: 0 = Blank (no outline) 1 = Single lines 2 = Double lines 3 = Double vert, Single horiz 4 = Single vert, Double horiz 5 = Single horiz, No vert 6 = Double horiz, No vert 7 = Solid border, all around 8 = Light Hatch, all around 9 = Medium Hatch, all around 10 = Heavy Hatch, all around 11 = Same as 5, with no border 12 = Same as 6, with no border 13 = Same as 0, with no border (c) 1987-90 Barry Erick Page 7 (c) 1987-90 Barry Erick Page 7 PBWindow DocumentationPBWindow Documentation Shadow% This defines if you want a black Shadow% drop shadow, and if so, if you want that shadow to be transparent. There are 11 Drop Shadow types: 0 = None 1 = Left , solid 2 = Right , solid 3 = Left , transparent 4 = Right , transparent 5 = Left , Light Hatch 6 = Right , Light Hatch 7 = Left , Medium Hatch 8 = Right , Medium Hatch 9 = Left , Heavy Hatch 10 = Right , Heavy Hatch Racket% Defines whether you want noise Racket% when the window opens or closes. There are 2 valid values: 0 = No Racket or Noise 1 = Racket or Noise Bfc% BoxlineForegroundColor. This is Bfc% the color the BoxKind line will have if there is a boxline. For it to be the same as Fc, use a -1, otherwise all values for Fc are valid for Bfc. Bbc% BoxlineBackgroundColor. This is Bbc% the color the BoxKind line background will have if there is a boxline. For it to be the same as Bc, use a -1, otherwise all values for Bc are valid for Bbc. Note: If you have a shadow, do not use 0 (or Black) for best results. Table 1: Colors for Fc,Bc,Bfc, and Bbc Table 1 0 Black (16) 8 Gray (24) 1 Blue (17) 9 LtBlue (25) 2 Green (18) 10 LtGreen (26) 3 Cyan (19) 11 LtCyan (27) 4 Red (20) 12 LtRed (28) 5 Magenta (21) 13 LtMagenta (29) 6 Brown (22) 14 Yellow (30) 7 White (23) 15 Bright White (31) 16-31 Blinks Foreground Page 8 (c) 1987-90 Barry Erick Page 8 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Note that the minimum and maximum values for Wr, Wc, Wh, and Ww are dependent on the Shadow% value. The screen positions are normally 1 thru 80 across and 1 thru 25 up and down. When a shadow is involved, the bottom of the raster is always 1 more than Wh, as the width is also one greater than Ww specifies. If we are calling for a left drop shadow, then the starting column is actually one less than Wc, and so the minimum value is 2. For a right drop shadow, the maximum screen position is 79, as position 80 is taken by the shadow. ZoomBox This routine makes a window that grows in size as ZoomBox it is made. Other than this, it is exactly the same as MakeBox. Refer to MakeBox on page 4 for details of the parameters. Rackett This procedure makes a noise if the variable Rackett NoNoise% is %True. If NoNoise% is %False, this procedure then does nothing. The Calling sequence is: Call Rackett RemoveBox This routine removes a opened window. It removes RemoveBox the last opened window, and there are no parameters to pass. The Calling sequence is: Call RemoveBox GetAttribute This function returns a integer attribute when GetAttribute supplied with Forecolor and BackColor, as defined in Table 1. Usage: variable% = GetAttribute(ForeColor%,_ BackColor%) GetForAndBack This procedure supplies the ForeColor and GetForAndBack BackColor integers from a supplied integer attribute. Calling sequence is: Call GetForAndBack(attr%,forecolor%,_ backcolor%) where forecolor and backcolor are as defined in Table 1. PrtBox This procedure prints a string within the PrtBox currently (last) open window. A Call MakeBox() must have first been made. Usage: Call PrtBox(r1%,c1%,stuff$) (c) 1987-90 Barry Erick Page 9 (c) 1987-90 Barry Erick Page 9 PBWindow DocumentationPBWindow Documentation where: o r1% = Row within the window, not screen. First available row is 1, and is referenced to Wr+1. The last row available is Wh-1. o c1% = Column within the window, not screen. First available column is 1, and is referenced to Wc+1. The last column is Ww-1. o Stuff$ = The string to print at the Fc and Fc used when the window was made with MakeBox. BoxTitle This places a title on the border line of a box BoxTitle already made with a call to MakeBox(). There are 12 places, and values, that can be passed. Usage is: Call BoxTitle(Where%,What$,Bxfc%,Bxbc%) Where: Where% Defines one of 12 places around Where% the window box for the title to be: Table 2: Box Title LocationsTable 2 Horizontal Vertical 1 = Top Left 7 = Middle Left 2 = Top Middle 8 = Middle Right 3 = Top Right 9 = Top Left 4 = Bot Left 10 = Bot Left 5 = Bot Middle 11 = Top Right 6 = Bot Right 12 = Bot Right What$ Is the Text to place Where. Make What$ sure it fits. If this is Null, then the border is rebuilt. Also, if first character of What$ = chr$(234) (Ω), then the title border location is rebuilt using the new string. Bxfc% Is the integer color What$ will Bxfc% be. It may be any valid foreground color as defined in Table 1. It will be the same as Bfc if made equal to -1. Bxbc% Is the integer color the Bxbc% background of What$ will be. It Page 10 (c) 1987-90 Barry Erick Page 10 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation may be any valid background color as in Table 1. It usually looks best if it is the same as Bbc. Making it equal to -1 will make it equal to Bbc. BoxScroll This scrolls the text within a window up or down BoxScroll one row at a time at a specified color. This allows you to scroll off text in one color, and bring it back in another color. The entire window is cleared by calling this routine the number of rows there is in the window. The calling sequence is: Call BoxScroll(Direction%,Fcolor%,Bcolor%) Where: Direction% can be one of two values: Direction% 0 = Up one row 1 = Down one row FColor% Is the color text will be on the FColor% new row, if any is pulled to it, which it usually isn't. Valid FColors are the same as Fc in Table 1. A value of -1 will make it the same as Fc. BColor% Is the color of the row BColor% background that is scrolled in. Valid BColors are the same as Bc, as shown in Table 1. A value of -1 will make it the same as Bc. CtrBox This is the same as PrtBox, except it centers the CtrBox text on the row within the window. The Calling sequence is: Call CtrBox(r1%,Stuff$) Where: r1% Is the row within the window to r1% center the string Stuff$. Stuff$ Is the text to center within the Stuff$ window at row r1. The color was defined when the window was made with MakeBox(). CtrAllBox This is similar to CtrBox, except it centers the CtrAllBox text in the window, both vertically and horizontal. The calling sequence is: (c) 1987-90 Barry Erick Page 11 (c) 1987-90 Barry Erick Page 11 PBWindow DocumentationPBWindow Documentation Call CtrAllBox(Which%,HowMany%,Stuff$) Where: Which% Is the number of HowMany this Which% line of Stuff$ is. HowMany% Is the Total Number of lines that HowMany% are to be centered in the current window. Stuff$ Is the text to center within the Stuff$ window at Which line of HowMany lines. PrtEOL This does a erase to EndOfLine using the current PrtEOL attribute of the window. The calling sequence is: Call PrtEol(Row%,Column%) Where: Row% Is the row within the window, not Row% screen. First available row is 1, and is referenced to Wr+1. The last row available is Wh-1. Column% Is the column within the window, Column% not screen. First available column is 1, and is referenced to Wc+1. The last column is Ww-1. PrtEOLBox This prints a string within the window and then PrtEOLBox does a EOL using the PrtEol procedure. The calling sequence is: Call PrtEOLBox(row%,column%,stry$) Where: Row% Is the row within the window, not Row% screen. First available row is 1, and is referenced to Wr+1. The last row available is Wh-1. Column% Is the column within the window, Column% not screen. First available column is 1, and is referenced to Wc+1. The last column is Ww-1. Stry$ Is the string to print. Stry$ NewBoxColor This procedure sets the saved attributes of the NewBoxColor current window to your specified color. This will Page 12 (c) 1987-90 Barry Erick Page 12 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation allow the next action within that window to be of the new color. The calling sequence is: Call NewBoxColor(frewe%,bvcxv%) Where: Frewe% Is the foreground color. Frewe% Bvcxv% Is the background color. Bvcxv% BuildMenu This procedure allows you to use the window BuildMenu system for menus. Several types and actions are provided. You can have a pointer to point to items, a highlighted bar the width of the window, or the width of the string. The first letter can be highlighted. Selection can be made on all types by moving the bar and hitting Enter, or by hitting the highlighted first letter. Another option allows you to hit the highlighted character, and if there is more than one item starting with that character, the next hit of the same letter will select the next item, and this will continue and wrap around to the first. Selection is done with the Enter key or automatically in this instance. To use the feature, you must build a list of items and assign them to the string array mList$(). This array is DIMmed to 20. The last item in the list must be either a null string 2 ("") or the string "@#$" . This signals the end of the list. For example: MList$(1) = "One" MList$(2) = "Two" MList$(3) = "@#$" (or MList$(3)="" Would signal to build a menu consisting of two items. The calling sequence is: CALL BuildMenu(mitem%,bmstart%,bmFirst%,_ bment%,bmffore%,bmback%,_ bmhfore%,bmhback%,bmbar%,_ Mlist$(),Auto%,PointerColor%) Where: mitem% Is the item number selected mitem% within the menu. _________________________________________________________________ 2. This string is kept for compatibility reasons. (c) 1987-90 Barry Erick Page 13 (c) 1987-90 Barry Erick Page 13 PBWindow DocumentationPBWindow Documentation bmstart% Is the item number to start with. bmstart% This item will be the highlighted or pointed to item. Normally this is 1. 3 bmFirst% If True , this sets the first bmFirst% letter in each menu item to be highlighted, and selection by the first character is allowed. If False, then this is not possible. bment% If True, this means the Enter key bment% is required on first letter selection. If False, then hitting the highlighted first character selects that item. Note that True allows several items to share the same first character, while setting this false will require all items to have a unique first character. bmffore% This is the foreground color to bmffore% use for the first character highlight. -1 means to use the same as the box uses. bmfback% This is the background color to bmfback% use for the first character highlight. -1 means to use the same color as the box uses. bmhfore% This is the foreground color for bmhfore% the menu item when highlighted with a bar. -1 means to use the same color as the box. bmhback% This is the background color for bmhback% the menu item when highlighted with a bar. -1 means to use the same color as the box. _________________________________________________________________ 3. Defined in PBWindow.INC, %True = -1 and %False = 0 Page 14 (c) 1987-90 Barry Erick Page 14 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation bmbar% This selects the type of bar: bmbar% Table 3: Bars GeneratedTable 3 0 = No Highlight 1 = The Item is Highlighted 2 = The Box Width is Highlighted 3 = An Arrow is used 4 = An Arrow is used and the item is Highlighted Mlist$() This is the list for the menu as Mlist$() described above. Auto% This variable, if %True, will Auto% allow the menu to return the current highlighted item as the selection after a timeout, or by the user, whichever occurs first. If %False, the user must make the selection. The variable, AutoBuildTime% determines the amount of time waiting. If this routine times out, and is returned automatically, Auto% will return %True. If the user hit a key to select an item, then Auto% will return %False. PointerColor% PointerColor% allows the pointer PointerColor% or arrow, to be a different color than the highlight. If this is set to a -1, then the color of the pointer will be the same as the highlight defined by the variable bmhfore%. This variable must be passed even if you do not use an option that specifies a pointer. Also, see the variables Bar0to2Off% and Bar3or4Off% in Appendix A.0. PrtAttrBox This prints a string within the current window PrtAttrBox using a different attribute than the default, but does not change the attributes for the window for subsequent calls. The calling sequence is: Call PrtAttrBox(Row%,Column%,String$,Fore%,_ Back%) Where (c) 1987-90 Barry Erick Page 15 (c) 1987-90 Barry Erick Page 15 PBWindow DocumentationPBWindow Documentation Row% Is the row within the current Row% window to use. Column% Is the row within the current Column% window and current line. String$ This is the string to print at String$ Row%, Column%. Fore% This is the foregound color to Fore% use. If set to -1, the default foreground color for the window is used. Back% This is the background color to Back% use. If set to -1, the default background color is used. ClearBox This clears the current window to the foreground ClearBox and background color you specify. The calling sequence is: Call ClearBox(Fore%,Back%) Where: Fore% Is the foreground color to use. Fore% If set to -1, the default foreground color is used. Back% Is the background color to use. Back% If set to -1, the default background color is used. ReColor This allows you to recolor the last window. This ReColor was designed to do this because it would be hard to work a routine to recolor only the portion of a window that another one isn't sitting on, which can happen if we allowed recoloring of more than the last window. The calling sequence is: Call ReColor(Fore%,Back%,BorderFore%,_ BorderBack%) Where: Fore% Is the new foreground color to Fore% use. If set to -1, the foreground color will not change. Back% Is the background color to use. Back% If set to -1, the default background color is used for no Page 16 (c) 1987-90 Barry Erick Page 16 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation apparent change in the background. BorderFore% This carries the new border BorderFore% foreground color. Again, if set to -1, the color remains unchanged. BorderBack% As in the others, this holds the BorderBack% new background color and if set to -1 does not change. WriteScreenArea This is called by MakeBox internally and really WriteScreenArea should not be used externally. It is provided here as a way to write to an area without keeping track of what you are doing. When Remove box is called after this, the previous window and this one is removed. Not recommended to use, but the usage is: Call WriteScreenArea(UpperLeftRow%,_ UpperLeftCol%,_ NumOfRows%,NumOfCols%,_ Text$,Attrs$) Where: UpperLeftRow% is the upper left row number, 0 UpperLeftRow% to 24 UpperLeftCol% is the upper left column of the UpperLeftCol% box, 0 -79 NumOfCols% is the total number of columns NumOfCols% from the UpperLeftCol. Text$ is the text to write to the Text$ screen. The length of the string is determined to be no greater than NumOfCols, as this routine is used to write not the entire box, but one row of the box. Attrs$ is the attribute to use and must Attrs$ equal the length of text$ SaveScreenArea This is also called by MakeBox internally and SaveScreenArea should not be used without totally understanding the code. It is made PUBLIC so some advanced uses may be used externally of the program. Not recommended to use, the usage is: (c) 1987-90 Barry Erick Page 17 (c) 1987-90 Barry Erick Page 17 PBWindow DocumentationPBWindow Documentation Call SaveScreenArea(UpperLeftRow%,_ UpplerLeftCol%,_ NumOfRows%,NumOfCols%,_ SaveText$,SaveAttr$) where: UpperLeftRow% is the upper left row number, 0 UpperLeftRow% to 24 UpperLeftCol% is the upper left column of the UpperLeftCol% box, 0 -79 NumOfCols% is the total number of columns NumOfCols% from the UpperLeftCol. SaveText$ is the text retrieved from the SaveText$ screen. The length of the string is equal to NumOfCols, as this routine is used to read not the entire box, but one row of the box. SaveAttr$ is the attribute used on the SaveAttr$ screen and equals the length of text$ PBWindowInit This routine is used by the $Include file. It PBWindowInit returns the screen segment and the retrace mode. It also Dims dynamically all arrays. If RetraceMode% is 0 then we do no retrace on screen writes, else we do check, for a slower display. This happens in CGA modes. If you need to use this just to see the routines, the calling sequence is: CALL PBWindowInit Returned: ScreenSegment% returns the ScreenSegmentscreen ScreenSegment% segment of the adapter, either &HB000 or &HB800. RetraceMode% returns the retrace mode. If you RetraceMode% have a cga adapter, then we use retrace protection, and this will return non zero. If zero, then there is no wait for retrace, and screen writes are much faster. You can fool PBWindows into not using retrace with your program by using the statement Retrace% = 0 after the $Include statement in your program. Page 18 (c) 1987-90 Barry Erick Page 18 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation ScreenInit This sub returns the ScreenSegment and Retrace ScreenInit mode, unlike PBWindowInit, which Dims many arrays and should only be called once. This may be called as often as you wish if you need to update the current modes. The calling sequence is: Call ScreenInit(ScreenSegment%,RetraceMode%) Returned: ScreenSegment% and RetraceMode% See PbWindowInit for details. ErrorChecker This sub is used internally, but is made Public ErrorChecker for use within the registered PBWSmall version to allow any optional pbu access to it. If you need to use it, the calling sequence is: Call ErrorChecker(ErrorMessage$,ErrorCode%) Returned: A window with the message and code A prefix of PBWindow Error is tacked onto it. The Function/Sub name where the call came from is shown. WhatCPU This Function returns the cpu type as an integer. WhatCPU 4 For example : Print "The CPU is a ";WhatCpu% Note: %MaxWindow is no longer supported. This constant has been changed to Max.Window%, an integer meant to be set in your program to equal the maximum number of windows you will have open at any one time. This must be used prior to invoking the $Include at any one time metastatement. Also, the variable AutoBuildTime% should be set at this time if you want something other than the default of 0. A new Constant is introduced, which must, for the distributed version, be set to 0. It is %PBWSmall. Example: AutoBuildTime% = 60 'set timeout to 60 seconds Max.Window% = 14 'set a max of 14 windows at any one timeany one time %PBWSmall = 0 'necessary constant that MUST be placed ' prior to the next statement or the ' program will not compile. $Include "PBWindows" _________________________________________________________________ 4. This is not part of PBWindow. It is from CPU.OBJ (c) 1987-90 Barry Erick Page 19 (c) 1987-90 Barry Erick Page 19 PBWindow DocumentationPBWindow Documentation 5 The Demo PWDemo.Bas 5 The Demo PWDemo.Bas The demo file does nothing but demonstrate the routines available in PBWindow. This file is menu driven, the menu being one built from the PBWINDOW unit. Following the instructions in section 3 on page 4 will show you how to compile this demo. Briefly, the file, PWDemo.Bas goes to your \PB default directory, PBWindow.INC to your \PB\INC directory, PBWObj.OBJ to your \PB\OBJ directory, and PBWindow.PBU to your \PB\PBU directory. The demo has directives in it to compile to .exe, turn off error tests, and to turn off break tests. Also, Library routines are stripped, as they are not needed for the demo. If you use the Command Line Compiler (PBC.EXE), and you do not have a PBC.CFG (configuration) file, you may place all the files in the same directory as your PBC.EXE file and simply type PBC PWDEMO /CE to compile this, as the demo program has metastatements in it to direct the compiler as to its duties. One .PBU file, DayDate.PBU, is only used for the demo and is not needed to use PBWindows. When you run the demo, either you make the selections by selecting and hitting enter on the main menu, and spacebar when asked to, or do nothing. The demo will automatically run if the users does nothing for 30 seconds. At that time, it changes to a 3 second timeout to make for a faster moving demo than if this were left at 30 second. 6 Potpourri 6 Potpourri 6.1 Support available 6.1 Support available The author may be contacted in the Spectra area in the IBM Vendor B Forum on Compuserve (g PCVenB, Section 12) or in the Spectra Category of the IBM RT on GEnie (page 615 CATegory Spectra And PowerBASIC). My Compuserve ID is 75300,214 and my GEnie ID is B.ERICK. 6.2 Source Code Available 6.2 Source Code Available 5 Source code to the unit and a printed manual are available . The fact that this is available makes this Shareware. You are not required to purchase or register this program to use it for non- commercial use. Source code with a manual is $25. If you want this, send the appropriate amount, including 6% Pennsylvania State tax for Pennsylvanian's, to: Barry Erick 28 Ridge Street Dallas, PA 18612 _________________________________________________________________ 5. Source to the Object code is not available. Page 20 (c) 1987-90 Barry Erick Page 20 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Commercial users must register two copies. Only one manual and disk will be sent, but the registration of 2 copies is all that is needed for commercial license terms. Also let us know what program this will be used in. If this is included in a commercial program, then an additional licence fee will be invoked. Details for this licensing is available from the author. If you find this program useful, but do not need the source code, why not register as a way of saying thanks for the routines? It would be greatly appreciated. Be sure to state what disk format you want. This can be supplied on either 5 1/4 or 3.5 inch low density disks at no extra cost until further notice. Please specift if you want the version for PowerBASIC version 2.0x or for PowerBASIC Power Pak, version 2.1. If not specified, the PowerPak version will be sent. 6.3 Update availability 6.3 Update availability The .pbu file will need to be updated as new major versions of PowerBasic become available, and possibly a minor upgrade will require this, also. Therefore, the .pbu file will be made available to users. If the .Obj file requires a update, it too will be made available. This availability may mean electronic distribution via CIS EasyPlex, or GEnie's GEMail, or it might mean a disk will be sent to you. In any case, the new version of the entire program will replace the current version. Contact the author if you need upgrade information when newer versions of PowerBasic are released. 6.4 Distribution of the programs 6.4 Distribution of the programs The source code for PBWindow.PBU, PBWindow.INC, PWDemo.Bas PBWObj.OBJ and DayDate.PBU are copyright material and are not in the Public Domain. The author retains property rights to the routines. You may include the files PBWindow.PBU, PBWObj.OBJ and PBWindow.INC in your programs, but not the source code to the unit, called PBWindow.Bas. This program, consisting of the files PWDemo.Bas, PBWindow.Inc, PBWindow.PBU , PBWObj.OBJ and PBWindow.DOC may be distributed to BBS's, commercial and private, provided they are distributed together, and the file group is named PBWindow.* or PBWndo.* if the file name limit is 6 characters, as it is on Compuserve. The file extension, as noted by the *, shall reflect the the grouping method, such as .ARC, .PKA, .ZIP, or .LHZ. In addition, the files may be included in a self-extracting file with the name PBWndo.EXE, or PBWindow.EXE made by .LHZ OR .ZIP only. This restriction is placed on the self-extracting file because of the favorable overhead that LHarc and PKZip places in its self extracting files. These files may also be distributed by clubs and user groups providing no more than $10 is charged for expenses and handling while distributing the files below. Note that this fee charged does not register the program. (c) 1987-90 Barry Erick Page 21 (c) 1987-90 Barry Erick Page 21 PBWindow DocumentationPBWindow Documentation The following files may be freely copied and distributed as long as they are kept in a group: PWDemo.BAS <-- The source to the demo PBWindow.INC <-- The $Include file to $Link PBWindow PBWindow.PBU <-- The actual utility "PBWindows" PBWObj.OBJ <-- The Object code for PBWindows PBWindow.DOC <-- This file DayDate.PBU <-- Used in the demo only Cpu.Obj <-- Used in the demo only Vendor.Doc <-- Information for Shareware Vendors Readme <-- If present, contains late info These files, are part of the registration package and may not be freely copied and distributed: PBWindow.Bas <-- The source to PBWindow.PBU DayDate.Bas <-- The source to DayDate.PBU 6 PBWOBJ.Asm <-- The source to PBWObj.OBJ 7 Cpu.Asm <-- The source to Cpu.Obj _________________________________________________________________ 6. Not currently available as source. 7. Not currently available as source. Page 22 (c) 1987-90 Barry Erick Page 22 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation 6.5 Warranty and Disclaimer 6.5 Warranty and Disclaimer Users of PBWindows must accept this disclaimer of warranty: "PBWindows is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of PBWindows." 6.6 Copyright Notices 6.6 Copyright Notices PBWindow.PBU, PBWindow.BAS PBWObj.OBJ PBWObj.ASM PBWindow.INC, PWDemo.BAS, PWDemo.EXE DayDate.BAS DayDate.Pbu Cpu.Asm Cpu.Obj (c) 1987-1990 Barry Erick PowerBASIC (c) 1990 Robert S. Zale LHarc (c) 1988-1989 Haruyasu Yoshizaki (Yoshi) ARC (c) 1985-1989 System Enhancement Associates, Inc. PKPak, PKUnpak (c) 1986-1989 PKWare, Inc. PKZip, PKUnzip (c) 1989 PKWare, Inc. Other trademarks and Copyrights by the copyright holder. (c) 1987-90 Barry Erick Page 23 (c) 1987-90 Barry Erick Page 23 PBWindow DocumentationPBWindow Documentation Page 24 (c) 1987-90 Barry Erick Page 24 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Appendix AAppendix A Public VariablesPublic Variables These are the Public Variables in the file PBWindows. They may be referenced to in other areas of the program, but should not be altered nor reused for your own use. Attrs%(MaxWindow%) Current attribute for which window. Attrs%(MaxWindow%) AutoBuildTime% The time for the BuildMenu to wait AutoBuildTime% for user input before automatically making the selection. The parameter Auto% in BuildMenu, must be %True for this to mean anything. The valid values of AutoBuildTime% are 1 to 15000 seconds. The demo limits the values to 20 to 15000 seconds. IsColr% If true, this system was in color IsColr% when PBWindow started. This does not limit PbWindows to color, but lets you decide if color is available. Use ScreenSegment to decide if you even want to try color. If ScreenSegment is &B000 then we do have Hercules or IBM Mono mode, and color should not be attempted. VidMode% may also be looked at. If it is 7, then this is a mono mode. Bar0to2Off% This offset is added to the Bar0to2Off% starting column specified by the BmBar% variable when BmBar is < 3. It is defaulted to 3. This is active in Menu display only. Bar3or4Off% Similar to Bar0to2Off%, this works Bar3or4Off% for values of BmBar% being 3 or 4. The default is 0, and this, too, is only active in Menu display modes. BoxBorderAttrs%(MaxWindow%) The attributes of the border for BoxBorderAttrs%(MaxWindow%) each window. (c) 1987-90 Barry Erick Page 25 (c) 1987-90 Barry Erick Page 25 PBWindow DocumentationPBWindow Documentation BoxKinw%(MaxWindow%) Keeps the window kind for each BoxKinw%(MaxWindow%) wpt%. Max.Window% Variable carries the maximum number Max.Window% of windows. Mbc% MakeBoxBackgroundColor holds the Mbc% last windows Background color. Mbbc% MakeBoxBorderBackColor holds last Mbbc% window's border background color used. Mbfc% MakeBoxBorderForeColor holds last Mbfc% window's border foreground color. Mfc% MakeBoxForegroundColor holds the Mfc% foreground color of the last window. Noise%(MaxWindow%) Noise information for which window. Noise%(MaxWindow%) Note: You can also control how a window is removed by changing the value in this array. Normally, a window is removed with noise if Racket was made when the window was made, and vice versa. To make a quiet removal of a noisy window, set Noise(WindowNumber) = 0 and to make it noisy, if the window was quite, make Noise(WindowNumber) = 1. ScreenSegment% This variable carries the video ScreenSegment% segment address. Shadows%(MaxWindow%) Shadow information for which Shadows%(MaxWindow%) window. RetraceMode% This variable is used to see if we RetraceMode% need to check for snow. If VidMode% = 7, then do NOT make this %True. It will lock up a mono system. You can force this off, by placing the command, RetraceMode = 0 right agter the $include PBwindow.Inc statement in your program. PBWc%(MaxWindow%) Window Column of which window. PBWc%(MaxWindow%) PBWh%(MaxWindow%) Window height of which window. PBWh%(MaxWindow%) Page 26 (c) 1987-90 Barry Erick Page 26 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Wpt% Current window pointer, if 0, no Wpt% windows are open. PBWr%(MaxWindow%) WindowRow of which window. PBWr%(MaxWindow%) PBWw%(MaxWindow%) Window Width of which window. PBWw%(MaxWindow%) Mlist$(20) For carrying the items in a menu. Mlist$(20) NoNoise% If 0, then racket or noise is NoNoise% allowed through the various routines. If other than 0, then noise is not allowed, even if the internal sub Rackett is called. UnderDevelopment% This variable controls error UnderDevelopment% checking while you develop your program. It defaults to %False, but you may set it in your program, after the $include "PbWindow.Inc" metastatement, to allow error checks to be made in several area of PBWindow.PBU. See the Appendix Error Codes for details of the errors. VidMode% This returns the video mode the VidMode% system was in when PbWindows was initialized. The most common text color mode is 3, and the mode to look for is 7. If this is 7, then we have a Hercules or IBM Monograph adapter. If we do, then do not use any colors and definitely do not modify the variable RetraceMode%, as that cannot be %true for a mono system. It is best to leave RetraceMode alone, anyway. (c) 1987-90 Barry Erick Page 27 (c) 1987-90 Barry Erick Page 27 PBWindow DocumentationPBWindow Documentation Page 28 (c) 1987-90 Barry Erick Page 28 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Appendix BAppendix B Error CodesError Codes If the variable UnderDevelopment% is %True, error checking is enabled to check the parameters you send to PBWindows. Along with the name of the Function/Sub where is error is found, these errors are printed in a window. The program will terminate to allow you to correct the problem. Be sure to make UnderDevelopment% %False once the program is debugged. Here are the error codes in the program: 1 Starting Column must be > 0 From MakeBox or ZoomBox, 1 Starting Column must be > 0 you specified a starting column less than 0. 2 Starting Column must be > 1 You specified a Left Drop 2 Starting Column must be > 1 Shadow and the starting column is less than 2. There must be room for a shadow resulting in a starting column >1. 3 Start Column + Width must be <=80 Since the screen width is 3 Start Column + Width must be <=80 80, you can't have a wider window than the screen width. 4 Start Column + Width must be < 80 You specified a right 4 Start Column + Width must be < 80 shadow, which requires one more space than the widnow width. The drop starting position and the width specified would cause the display to go off the current line. 5 Start Row must be => 0 You specified a starting 5 Start Row must be => 0 row above the screen by specifying a row less than 0. 6 Start Row must be <= 25 You specified a starting 6 Start Row must be <= 25 position at the end of the screen. (c) 1987-90 Barry Erick Page 29 (c) 1987-90 Barry Erick Page 29 PBWindow DocumentationPBWindow Documentation 7 Ending Row must be <= 26 You specified a starting 7 Ending Row must be <= 26 row and number of rows that goes off the screen. 8 Ending Row must be <25 You are using a shadow, 8 Ending Row must be <25 which requires one row at the bottom and specifed a starting row and number of rows, that when added to the shadow row, would take the image off the screen. 9 Starting Column must be < 79 You specified a starting 9 Starting Column must be < 79 column at the rightmost side of the screen. 10 No Windows Open You must call either 10 No Windows Open MakeBox for Zoom Box to open a window before you can print in the window. 11 Too Many Windows Open You exceeded the 11 Too Many Windows Open Max.Window% limit on the number of open windows. This defaults to 5 unless you set this variable to something else before the $Include "PBWindow.Inc" metastatement in your program. Page 30 (c) 1987-90 Barry Erick Page 30 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation Appendix CAppendix C SHAREWARESHAREWARE C.1 Definition of Shareware C.1 Definition of Shareware Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated on page 23. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. C.2 Ombudsman C.2 Ombudsman This program is produced by a member of the Association of Shareware Professionals (). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at P.O. Box 5786, Bellevue, WA 98006 or send a Compuserve message via easyplex to ASP Ombudsman 70007,3536 (c) 1987-90 Barry Erick Page 31 (c) 1987-90 Barry Erick Page 31 PBWindow DocumentationPBWindow Documentation Page 32 (c) 1987-90 Barry Erick Page 32 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation IndexIndex $INCLUDE 5 Automatic Running 4, %MaxWindow 19 20 %PBWSmall 4, 19 Compiling 6 Running 20 A Direction 11 A ASP See: Association of Distributing the ____ Shareware programs 21 Professionals Down 11 Association of drop shadow 2, 8 Shareware Professionals 31 EE Auto 15 ErrorChecker 19 AutoBuildTime 15, 19 Explode See:____ Zoom,Zooming BB Back 16 FF BackgroundColor 7, 13 ForegroundColor 7, 13 BoxKind 7 BoxlineBackgroundColor GG 8 GEnie 20 BoxlineForegroundColor GetAttribute 9 8 GetForAndBack 9 BoxScroll 11 BoxTitle 10 HH BuildMenu 13 Hercules 3 C K C K Centering 11 Kinds of Windows See:____ ClearBox 16 BoxKind CLS See: ClearBox____ column 17, 18 LL Command Line Switch 5 lines 7 commercial license 21 Locked up system 26 compile 6 Compiling 4 MM Compuserve 20 MakeBox 6, 9, 10, 11, Copyright 31 17 CtrAllBox 11 Manual CtrBox 11 printed 20 Max.Window 4, 5, 19 D Menu 13 D DayDate.PBU 20 metastatement 4 Demo mList 13 About 20 Mono 3 AutoBuildTime 4 (c) 1987-90 Barry Erick Page 33 (c) 1987-90 Barry Erick Page 33 PBWindow DocumentationPBWindow Documentation N V N V NewBoxColor 12 Variables Noise 1, 8 Attrs 17 Number of Windows See: Attrs(MaxWindow%) 25 ____ Max.Window Auto 15 AutoBuildTime 15, 25 O Back 16 O Ombudsman 31 Bar3or4Off% 25 Bar0to2Off% 25 P Bbc 8 P PBWindowInit 18 bc 7 PointerColor 15 BColor 11 pop-up windows 4 Bfc 8 Power Pak 1 bmbar 14 PowerBASIC 2.1 1 bment 14 Printed manual 20 bmfback 14 PrtAttrBox 15 bmffore 14 PrtBox 9 bmFirst 14 PrtEOL 12 bmhback 14 PrtEOLBox 12 bmhfore 14 bmstart 13 R BorderBack 17 R Racket 26 BorderFore 17 Rackett 9 BoxBorderAttrs(MaxWindow%) ReColor 16 25 recolor 1 BoxKind 7 RemoveBox 6, 9 BoxKinw%(MaxWindow%) Restore Title 10 25 RetraceMode 18 Bvcxv 13 Row 6, 10 Bxbc 10 row 11 Bxfc 10 row 11 c1 10 row number 7 Column 12, 16 row 12, 16, 17, 18 fc 7 FColor 11 S Fore 16 S SaveScreenArea 17 Frewe 13 ScreenInit 18 HowMany 12 ScreenSegment 18 IsColr% 25 Scroll See: BoxScroll Max.Window% 26 ____ Shadow 7 Mbbc 26 Shareware 20, 31 Mbc 26 Source code Mbfc 26 availability 20 Mfc 26 Support 20 mitem 13 mList$ 15 T Mlist$(20) 27 T Title See: BoxTitle Noise(MaxWindow%) 26 ____ Tracking 1 NoNoise 27 NoNoise% 9 U NumOfCols 17, 18 U Up 11 PBWc(MaxWindow%) 26 PBWh(MaxWindow%) 26 PBWr(MaxWindow%) 27 Page 34 (c) 1987-90 Barry Erick Page 34 (c) 1987-90 Barry Erick PBWindow DocumentationPBWindow Documentation PBWw(MaxWindow%) 27 Wc 6 PointerColor 15 Wh 6 r1 10, 11 What$ 10 Racket 8 Where 10 RetraceMode 26 Which 12 Row 12, 15 Wpt 26 SaveAttr$ 18 Wr 6 SaveText$ 18 Ww 7 ScreenSegment 18, 26 Shadows(MaxWindow%) WW 26 WhatCPU 19 String$ 16 WindowColumn 6 Stry$ 12 WindowHeight 7 Stuff$ 10, 11, 12 WindowRow 6 Text$ 17 WindowWidth 7 UnderDevelopment% 3, WriteScreenArea 17 5, 27, 29 UpperLeftCol 17, 18 ZZ UpperLeftRow 17, 18 Zoom 1 VidMode 27 ZoomBox 6, 9 (c) 1987-90 Barry Erick Page 35 (c) 1987-90 Barry Erick Page 35